---
title: Custom Components
description: Univer provides multiple ways to integrate custom components, allowing you to extend and customize its functionality. This guide will introduce several common methods.
icon: Component
---

Univer does not directly pass components as parameters to any rendering functions. You need to register the components with Univer through the Facade API before you can use them in various mounting points.

If you are not familiar with how to obtain an instance of the Facade API, you can refer to [Facade API](/guides/sheets/getting-started/facade).

<include cwd>content/guides/shared/ui/components.mdx</include>

#### Attach Popup to Cells

Using the `FRange.attachPopup` method, you can attach a custom popup to a specific cell range.

- A popup is a temporary DOM element attached to a cell, typically used to display transient status information and does not support persistent storage.
- You can use the [`FRange.attachPopup(popup: IFCanvasPopup)`](https://reference.univer.ai/en-US/classes/FRange#attachpopup) method to attach a custom popup to a specific cell range.
- The popup will attach to the edges of the cell and will automatically adjust its position and orientation if obstructed.

```tsx
// [!code word:MyCustomPopupComponent]
// You should register the component at an appropriate time (e.g., after Univer has loaded)
univerAPI.registerComponent(
  'MyCustomPopupComponent',
  () => <div>Hello Univer!</div>,
)

const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:J10')

// Attach the popup to the first cell of the range
// If `disposable` is null, it indicates that the popup was not added successfully
const disposable = fRange.attachPopup({
  componentKey: 'MyCustomPopupComponent',
})

// Remove the popup
disposable.dispose()
```

#### Attach Alert Popup

Using the `FRange.attachAlertPopup` method, you can attach an alert popup to the starting cell of a specified range.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')

const disposable = fRange.attachAlertPopup({
  key: 'unique-alert-key', // Unique identifier
  title: '这是一个警告！',
  message: '这是一个警告！',
  width: 300,
  height: 200,
  // 0: Information
  // 1: Warning
  // 2: Error
  type: 0,
})

// Remove the alert later
disposable.dispose()
```

#### Add Floating DOM to Worksheet

Using the `FWorksheet.addFloatDomToPosition` method, you can add a floating DOM to the worksheet.

- Before using this method, you need to install the `@univerjs/sheets-drawing-ui` plugin or the `@univerjs/preset-sheets-drawing` preset.
- The floating DOM is a draggable component that hovers over the worksheet and supports persistent storage.
- You should call this method after Univer has finished rendering.
- `componentKey`: The unique identifier for the component, used to reference it within Univer.
- [Full parameter definition](https://github.com/dream-num/univer/blob/dev/packages/sheets-drawing-ui/src/facade/f-worksheet.ts#L32)

```tsx
// [!code word:MyCustomFloatDOMComponent]
// You should register the component at an appropriate time (e.g., after Univer has loaded)
univerAPI.registerComponent(
  'MyCustomFloatDOMComponent',
  ({ data }) => (
    <div>
      Hello
      {data?.label}
      !
    </div>
  ),
)
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Add a floating DOM to the worksheet
// If `disposable` is null, it indicates that the floating DOM was not added successfully
const disposable = fWorksheet.addFloatDomToPosition({
  componentKey: 'MyCustomFloatDOMComponent',
  initPosition: {
    startX: 100,
    endX: 200,
    startY: 100,
    endY: 200,
  },

  // The data for the component
  data: {
    label: 'Univer',
  },
})

// Remove the floating DOM
disposable.dispose()
```
